<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Loading Files and Classes Dynamically - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.loader.load.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.loader.load.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.loader.html">Zend_Loader</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.loader.html">Zend_Loader</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.loader.autoloader.html">The Autoloader</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.loader.load" class="section"><div class="info"><h1 class="title">Loading Files and Classes Dynamically</h1></div>
    

    <p class="para">
        The <span class="classname">Zend_Loader</span> class includes methods to help you load files
        dynamically.
    </p>

    <div class="tip"><b class="tip">Tip</b><div class="info"><h1 class="title">Zend_Loader vs. require_once()</h1></div>
        

        <p class="para">
            The <span class="classname">Zend_Loader</span> methods are best used if the filename you need to
            load is variable. For example, if it is based on a parameter from
            user input or method argument. If you are loading a file or a
            class whose name is constant, there is no benefit to using
            <span class="classname">Zend_Loader</span> over using traditional <acronym class="acronym">PHP</acronym>
            functions such as <a href="http://php.net/require_once" class="link external">&raquo;  <span class="methodname">require_once()</span></a>.
        </p>
    </div>

    <div class="section" id="zend.loader.load.file"><div class="info"><h1 class="title">Loading Files</h1></div>
        

        <p class="para">
            The static method  <span class="methodname">Zend_Loader::loadFile()</span> loads a
            <acronym class="acronym">PHP</acronym> file. The file loaded may contain any <acronym class="acronym">PHP</acronym>
            code. The method is a wrapper for the <acronym class="acronym">PHP</acronym> function
            <a href="http://php.net/include" class="link external">&raquo;  <span class="methodname">include()</span></a>.
            This method returns boolean <b><tt>FALSE</tt></b> on failure, for example
            if the specified file does not exist.
        </p>

        <div class="example" id="zend.loader.load.file.example"><div class="info"><p><b>Example #1 Example of the loadFile() Method</b></p></div>
            

            <pre class="programlisting brush: php">
Zend_Loader::loadFile($filename, $dirs=null, $once=false);
</pre>

    </div>

        <p class="para">
            The <var class="varname">$filename</var> argument specifies the filename to load,
            which must not contain any path information.
            A security check is performed on <var class="varname">$filename</var>.
            The <var class="varname">$filename</var> may only contain alphanumeric characters,
            dashes (&quot;-&quot;), underscores (&quot;_&quot;), or periods (&quot;.&quot;).
            No such restriction is placed on the <var class="varname">$dirs</var> argument.
        </p>

        <p class="para">
            The <var class="varname">$dirs</var> argument specifies which directories to search for the
            file in. If the value is <b><tt>NULL</tt></b>, only the include_path
            is searched; if the value is a string or an array, the directory or directories
            specified will be searched, followed by the <span class="property">include_path</span>.
        </p>

        <p class="para">
            The <var class="varname">$once</var> argument is a boolean. If <b><tt>TRUE</tt></b>,
             <span class="methodname">Zend_Loader::loadFile()</span> uses the <acronym class="acronym">PHP</acronym>
            function <a href="http://php.net/include" class="link external">&raquo;  <span class="methodname">include_once()</span></a>
            for loading the file, otherwise the <acronym class="acronym">PHP</acronym> function
            <a href="http://php.net/include_once" class="link external">&raquo;  <span class="methodname">include()</span></a>
            is used.
        </p>
    </div>

    <div class="section" id="zend.loader.load.class"><div class="info"><h1 class="title">Loading Classes</h1></div>
        

        <p class="para">
            The static method  <span class="methodname">Zend_Loader::loadClass($class, $dirs)</span>
            loads a <acronym class="acronym">PHP</acronym> file and then checks for the existence of the class.
        </p>

        <div class="example" id="zend.loader.load.class.example"><div class="info"><p><b>Example #2 Example of the loadClass() Method</b></p></div>
            

            <pre class="programlisting brush: php">
Zend_Loader::loadClass(&#039;Container_Tree&#039;,
    array(
        &#039;/home/production/mylib&#039;,
        &#039;/home/production/myapp&#039;
    )
);
</pre>

        </div>

        <p class="para">
            The string specifying the class is converted to a relative path
            by substituting underscores with directory separators for your OS, and appending
            &#039;.php&#039;. In the example above, &#039;Container_Tree&#039; becomes &#039;Container\\Tree.php&#039; on Windows.
        </p>

        <p class="para">
            If <var class="varname">$dirs</var> is a string or an array,
             <span class="methodname">Zend_Loader::loadClass()</span> searches the directories in
            the order supplied. The first matching file is loaded. If the file
            does not exist in the specified <var class="varname">$dirs</var>, then the
            <span class="property">include_path</span> for the <acronym class="acronym">PHP</acronym> environment is
            searched.
        </p>

        <p class="para">
            If the file is not found or the class does not exist after the load,
             <span class="methodname">Zend_Loader::loadClass()</span> throws a
            <span class="classname">Zend_Exception</span>.
        </p>

        <p class="para">
             <span class="methodname">Zend_Loader::loadFile()</span> is used for loading, so the
            class name may only contain alphanumeric characters and the hyphen
            (&#039;-&#039;), underscore (&#039;_&#039;), and period (&#039;.&#039;).
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Loading Classes from PHP Namespaces</b><br /></span>
            

            <p class="para">
                Starting in version 1.10.0, Zend Framework now allows loading classes from
                <acronym class="acronym">PHP</acronym> namespaces. This support follows the same guidelines and
                implementation as that found in the <a href="http://groups.google.com/group/php-standards/web/psr-0-final-proposal" class="link external">&raquo; PHP
                Framework Interop Group PSR-0</a> reference implementation.
            </p>

            <p class="para">
                Under this guideline, the following rules apply:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                        Each namespace separator is converted to a
                        <b><tt>DIRECTORY_SEPARATOR</tt></b> when loading from the file system.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        Each &quot;_&quot; character in the <em class="emphasis">CLASS NAME</em> is converted to a
                        <b><tt>DIRECTORY_SEPARATOR</tt></b>. The &quot;_&quot; character has no special
                        meaning in the namespace.
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        The fully-qualified namespace and class is suffixed with &quot;.php&quot; when loading
                        from the file system.
                    </p>
                </li>
            </ul>

            <p class="para">
                As examples:
            </p>

            <ul class="itemizedlist">
                <li class="listitem">
                    <p class="para">
                        <span class="classname">\Doctrine\Common\IsolatedClassLoader</span> =&gt;
                        <var class="filename">/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php</var>
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <span class="classname">\namespace\package\Class_Name</span> =&gt;
                        <var class="filename">/path/to/project/lib/vendor/namespace/package/Class/Name.php</var>
                    </p>
                </li>

                <li class="listitem">
                    <p class="para">
                        <span class="classname">\namespace\package_name\Class_Name</span> =&gt;
                        <var class="filename">/path/to/project/lib/vendor/namespace/package_name/Class/Name.php</var>
                    </p>
                </li>
            </ul>
        </p></blockquote>
    </div>

    <div class="section" id="zend.loader.load.isreadable"><div class="info"><h1 class="title">Testing if a File is Readable</h1></div>
        

        <p class="para">
            The static method  <span class="methodname">Zend_Loader::isReadable($pathname)</span>
            returns <b><tt>TRUE</tt></b> if a file at the specified pathname exists
            and is readable, <b><tt>FALSE</tt></b> otherwise.
        </p>

        <div class="example" id="zend.loader.load.isreadable.example"><div class="info"><p><b>Example #3 Example of isReadable() method</b></p></div>
            

            <pre class="programlisting brush: php">
if (Zend_Loader::isReadable($filename)) {
    // do something with $filename
}
</pre>

        </div>

        <p class="para">
            The <var class="varname">$filename</var> argument specifies the filename to
            check. This may contain path information.
            This method is a wrapper for the <acronym class="acronym">PHP</acronym> function
            <a href="http://php.net/is_readable" class="link external">&raquo;  <span class="methodname">is_readable()</span></a>.
            The <acronym class="acronym">PHP</acronym> function does not search the
            <span class="property">include_path</span>, while
             <span class="methodname">Zend_Loader::isReadable()</span> does.
        </p>
    </div>

    <div class="section" id="zend.loader.load.autoload"><div class="info"><h1 class="title">Using the Autoloader</h1></div>
        

        <p class="para">
            The <span class="classname">Zend_Loader</span> class contains a method you can register with the
            <acronym class="acronym">PHP</acronym> SPL autoloader.  <span class="methodname">Zend_Loader::autoload()</span>
            is the callback method. As a convenience, <span class="classname">Zend_Loader</span> provides
            the  <span class="methodname">registerAutoload()</span> function to register its
             <span class="methodname">autoload()</span> method. If the <span class="property">spl_autoload</span>
            extension is not present in your <acronym class="acronym">PHP</acronym> environment, then the
             <span class="methodname">registerAutoload()</span> method throws a
            <span class="classname">Zend_Exception</span>.
        </p>

        <div class="example" id="zend.loader.load.autoload.example"><div class="info"><p><b>Example #4 Example of registering the autoloader callback method</b></p></div>
            

            <pre class="programlisting brush: php">
Zend_Loader::registerAutoload();
</pre>

        </div>

        <p class="para">
            After registering the Zend Framework autoload callback, you can
            reference classes from Zend Framework without having to load
            them explicitly. The  <span class="methodname">autoload()</span> method uses
             <span class="methodname">Zend_Loader::loadClass()</span> automatically when you
            reference a class.
        </p>

        <p class="para">
            If you have extended the <span class="classname">Zend_Loader</span> class, you can give an
            optional argument to  <span class="methodname">registerAutoload()</span>, to specify
            the class from which to register an  <span class="methodname">autoload()</span> method.
        </p>

        <div class="example" id="zend.loader.load.autoload.example-extended"><div class="info"><p><b>Example #5 Example of registering the autoload callback method from an
                extended class</b></p></div>
            

            <div class="example-contents"><p>
                Because of the semantics of static function references in <acronym class="acronym">PHP</acronym>,
                you must implement code for both  <span class="methodname">loadClass()</span>
                and  <span class="methodname">autoload()</span>, and the  <span class="methodname">autoload()</span>
                must call  <span class="methodname">self::loadClass()</span>. If your
                 <span class="methodname">autoload()</span> method delegates to its parent to
                call  <span class="methodname">self::loadClass()</span>, then it calls the
                method of that name in the parent class, not the subclass.
            </p></div>

            <pre class="programlisting brush: php">
class My_Loader extends Zend_Loader
{
    public static function loadClass($class, $dirs = null)
    {
        parent::loadClass($class, $dirs);
    }

    public static function autoload($class)
    {
        try {
            self::loadClass($class);
            return $class;
        } catch (Exception $e) {
            return false;
        }
    }
}

Zend_Loader::registerAutoload(&#039;My_Loader&#039;);
</pre>

        </div>

        <p class="para">
            You can remove an autoload callback. The
             <span class="methodname">registerAutoload()</span> has an optional second argument,
            which is <b><tt>TRUE</tt></b> by default. If this argument is
            <b><tt>FALSE</tt></b>, the autoload callback is unregistered from the
            SPL autoload stack.
        </p>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.loader.html">Zend_Loader</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.loader.html">Zend_Loader</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.loader.autoloader.html">The Autoloader</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.loader.html">Zend_Loader</a></li>
  <li class="active"><a href="zend.loader.load.html">Loading Files and Classes Dynamically</a></li>
  <li><a href="zend.loader.autoloader.html">The Autoloader</a></li>
  <li><a href="zend.loader.autoloader-resource.html">Resource Autoloaders</a></li>
  <li><a href="zend.loader.pluginloader.html">Loading Plugins</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>